Fauna

Querying Overview

Qarbine utilizes the Fauna Query Language (FQL) to access Fauna cloud data. Its native support for FQL enables a variety of analyses to be run running from

Analysis of your application data to

Analysis of your Fauna configuration (i.e., collections and roles).

A good starting point for understanding the FQL querying language is at https://docs.fauna.com/fauna/current/learn/query/

A high level overview of Fauna concepts can be found at https://docs.fauna.com/fauna/current/get-started/overview/

A general FQL starting point is at

https://docs.fauna.com/fauna/current/reference/fql/

Note that some queries such as “Role.all()” require a Fauna “admin” API key. It was observed that without the correct permissions an empty answer set is returned. The Qarbine administrator is responsible for configuring Qarbine access to Fauna. There is a guide for this within the “Tools;Administrator;Data Service Configuration” section at http://doc.qarbine.com.

Sample Analysis

Qarbine provides a robust set of features for flexible analysis. Here is an example that uses Qarbine Prompts, Data Sources, and Templates.

Running the template presents a prompt to the user with a list populated from an FQL query.

Choosing a customer proceeds with the running of the template. The results are shown below.

Details on how to accomplish this with Qarbine are in the “Tutorials;Other Databases” section of http://doc.qarbine.com.

Sample FQL Query

Running this

Order.byId( 413124772996579392)

results in the following

Selecting the first row shows the following on the right side

Notice that the items are an EmbeddedSet and the customer a DocumentReference. FQL provides ‘projection’ operators to obtain these object values as part of the Fauna answer set.

Using FQL Projections

FQL has a projection feature that permits the resolution of references into actual documents. For more information see https://docs.fauna.com/fauna/current/reference/fql/projection/

Below is an example query

Order.byCustomer( Customer.byId('111') )

The results are shown below.

The detail of the first element is shown below.

Below is an example query with projections.

Order.byCustomer( Customer.byId('111') ) {
  items,
  total,
  customer
}

The results are shown below with a few fields removed.

The detail of the first element is shown below.

Note the customer and the items field references have been resolved by Fauna into objects.

Using Pragmas to Manipulate Answer Sets

Overview

The queries to your data may be defined using multiple lines of text for formatting and other purposes. Qarbine pragmas allow the manipulation of the answer set after the initial reply from Fauna. There are a large number of programs described in the main Data Source Designer guide within the Tools section of doc.qarbine.com

Fauna Specific Pragmas

Like the ‘//’ comment lines above, there are a few recognized lines that are preprocessed out by Qarbine and not sent to the backend data.

Starts With	Description
resolveReferences	Provide a dotted path to the target object containing the references of interest. Resolve all of the references within that object for the fields specifically indicated. You can have multiple resolveReference pragmas, one for each specific object field. To resolve the single customer reference in each answer row use#pragma resolveReferences customer To resolve the customer and order reference in each answer row use #pragma resolveReferences itself, customer, order The “itself” path is simply shorthand for the answer row itself. To resolve all of the references in the answer row use #pragma resolveReferences * To resolve all of the item objects in the orders field of an answer row use #pragma resolveReferences orders.items
skipReferences	Provide a dotted path to the target object containing the references of interest. Resolve all of the references within that object except the fields specifically indicated. The following resolves all references except for the customer field of the answer row. #pragma skipReferences customer When there are multiple fields to skip in the first level of the answer set row use the following syntax #pragma skipReferences itself, customer, order

Starts With

Description

resolveReferences

Provide a dotted path to the target object containing the references of interest. Resolve all of the references within that object for the fields specifically indicated. You can have multiple resolveReference pragmas, one for each specific object field.
To resolve the single customer reference in each answer row use#pragma resolveReferences customer

To resolve the customer and order reference in each answer row use
#pragma resolveReferences itself, customer, order
The “itself” path is simply shorthand for the answer row itself.
To resolve all of the references in the answer row use
#pragma resolveReferences *
To resolve all of the item objects in the orders field of an answer row use
#pragma resolveReferences orders.items

skipReferences

Provide a dotted path to the target object containing the references of interest. Resolve all of the references within that object except the fields specifically indicated. The following resolves all references except for the customer field of the answer row.
#pragma skipReferences customer
When there are multiple fields to skip in the first level of the answer set row use the following syntax
#pragma skipReferences itself, customer, order

Applying Pragmas

Recall running this

Order.byId( 413124772996579392)

results in an answer set with a document which has the “items” field as an EmbeddedSet and the “customer” field as a DocumentReference. We can use FQL projections or pragmas to adjust the answer set. Native FQL is preferred because the action takes place at Fauna query time. For information on Fauna projections see https://docs.fauna.com/fauna/current/reference/fql/projection/

The Qarbine pragmas occur after the initial Fana answer set retrieval. Interactions occur with Fauna for each pragma and each to be resolved reference as well.

Running this

#pragma resolveReferences *
Order.byId( 413124772996579392)

results in references being resolved and a sample answer row of

Notice the items and customer references have been resolved into objects. This is similar to native FQL projections.

The standard Qarbine pragmas can be further used to adjust the final answer set. Running this

#pragma resolveReferences *
#pragma deleteFields id, ts, order
#pragma deleteFields items.id, items.ts
#pragma deleteFields customer.cart, customer.orders
Order.byId( 413124772996579392)

results in removing unwanted fields as shown below.

The “items” elements have 3 fields instead of 5. The main level has 3 fields removed. The customer field has 2 fields removed. It is recommended as possible to use the combination of native FQL projections along with the deleteFields pragma. This reduces the transfer size of the answer set, the amount of network traffic consumed , and the overhead of converting JSON text into objects.

Custom Output Shaping

There are times when you would like different field names or to create new field values on the fly. This query uses custom output shaping

Order.byCustomer( Customer.byId('111') ) {
  // Use custom keys
  order_items: .items,
  // Concatenate or transform values
  order_total: .status + ": " + .total,
  overall : .total,
  customer
}

The results are shown below.

The details of one of the elements is shown below.

Using Index Functions

Fauna provides index driven queries to retrieve data. Below are the indexes defined for the Product collection.

The initial FQL is shown below

Product.sortedByPriceLowToHigh()

The results are shown below.

The details of one of the elements is shown below.

Note the category value is a DocumentReference. FQL may not be able to project (resolve) this reference in which case Qarbine’s pragmas can be very useful.

Using the following querying containing pragmas

#pragma resolveReferences category
#pragma pullValuesUp category.name
#pragma deleteFields category, id, ts
Product.sortedByPriceLowToHigh()

the results are now

Fauna index requests do not provide projection support so the Qarbine pragmas were used to obtain the referenced documents. This completely avoids any coding of retrievals as Qarbine handles the resolving per the pragma lines.

Using User Defined Functions

A Fauna user defined function (UDF) is a set of one or more FQL statements stored as a reusable resource in the database. Like a stored procedure in SQL, a UDF can accept parameters, perform operations, and return results.

You can obtain a list of user defined function by running the following in Qarbine

#pragma sortResultBy name
Function.all()

A sample result is shown below.

UDFs that return results can be run depending on permissions and other factors. Consult your Fauna documentation and administrator for details.

Running this query

validateOrderStatusTransition("cart", "cart")

results in

The details are shown below.

Qarbine Virtual Queries

There are a few convenience queries which are mainly DBA oriented. These queries are recognized by the Qarbine driver and provide common database information.

Query	Description
list databases	Return a list of databases.
describe database	Return the details of the default database.
describe databases	Return the details of all the visible databases.
list collections	Return a list of collections.
describe collections	Provide details on all of the collections. This may take a while depending on your database structure.
describe collection COLLECTION	Provide details on the given collection.

See the “DBA Productivity” section of the online documentation for more details.

References

For more information see https://docs.fauna.com/fauna/current/reference/fql/

Fauna

Querying Overview​

Sample Analysis​

Sample FQL Query​

Using FQL Projections​

Using Pragmas to Manipulate Answer Sets​

Overview​

Fauna Specific Pragmas​

Applying Pragmas​

Custom Output Shaping​

Using Index Functions​

Using User Defined Functions​

Qarbine Virtual Queries​

References​

Querying Overview

Sample Analysis

Sample FQL Query

Using FQL Projections

Using Pragmas to Manipulate Answer Sets

Overview

Fauna Specific Pragmas

Applying Pragmas

Custom Output Shaping

Using Index Functions

Using User Defined Functions

Qarbine Virtual Queries

References